home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_1.3 / Read-Me1.3 / Autodocs1.3 / serial.doc < prev    next >
Text File  |  1988-07-26  |  20KB  |  531 lines
  1.  
  2. TABLE OF CONTENTS
  3.  
  4. serial.device/command/Break
  5. serial.device/command/Clear
  6. serial.device/command/Flush
  7. serial.device/command/Query
  8. serial.device/command/Read
  9. serial.device/command/Reset
  10. serial.device/command/SetParams
  11. serial.device/command/Start
  12. serial.device/command/Stop
  13. serial.device/command/Write
  14. serial.device/function/AbortIO
  15. serial.device/function/BeginIO
  16. serial.device/function/CloseDevice
  17. serial.device/function/OpenDevice
  18.  
  19.  
  20. serial.device/command/Break                     serial.device/command/Break
  21.  
  22.    NAME
  23.        Break -- send a break signal over the serial line
  24.  
  25.    FUNCTION
  26.        This command sends a break signal (serial line held low
  27.        for an extended period) out the serial port. This is accom-
  28.        plished by setting the UARTBRK bit of reg ADKCON. After a
  29.        duration (user specifiable via setparams, default 250000
  30.        microseconds) the bit is reset and the signal discontinued.
  31.        If the QUEUEDBRK bit of io_SerFlags is set in the io_Request 
  32.        block, the request is placed at the back of the write-request 
  33.        queue and executed in turn. If the QUEUEDBRK bit is not set, 
  34.        the break is started immediately, control returns to the 
  35.        caller, and the timer discontinues the signal after the 
  36.        duration is completed. Be aware that calling BREAK may
  37.     affect other commands such as ABORT, FLUSH, STOP, START, etc...
  38.  
  39.    IO REQUEST
  40.        io_Message      mn_ReplyPort initialized
  41.        io_Device       set by OpenDevice
  42.        io_Unit         set by OpenDevice
  43.        io_Command      SDCMD_BREAK
  44.        io_Flags        set/reset IO_QUICK per above description
  45.  
  46.    RESULTS
  47.        Error -- if the Break succeded, then Error will be null.
  48.            If the Break failed, then the Error will be non-zero.
  49.  
  50.  
  51. serial.device/command/Clear                     serial.device/command/Clear
  52.  
  53.    NAME
  54.        Clear -- clear the serial port buffers
  55.  
  56.    FUNCTION
  57.        This command resets the serial port's read buffer pointers.
  58.  
  59.    IO REQUEST
  60.        io_Message      mn_ReplyPort initialized
  61.        io_Device       set by OpenDevice
  62.        io_Unit         set by OpenDevice
  63.        io_Command      CMD_CLEAR
  64.  
  65.    RESULTS
  66.        Error -- If the Clear succeded, then io_Error will be null.
  67.                 If the Clear failed, then the io_Error will be non-zero.
  68.  
  69.  
  70. serial.device/command/Flush                     serial.device/command/Flush
  71.  
  72.    NAME
  73.        Flush -- clear all queued I/O requests for the serial port
  74.  
  75.    FUNCTION
  76.        This command purges the read and write request queues for the
  77.        serial device. Flush will not affect active requests.
  78.  
  79.    IO REQUEST
  80.        io_Message      mn_ReplyPort initialized
  81.        io_Device       set by OpenDevice
  82.        io_Unit         set by OpenDevice
  83.        io_Command      CMD_FLUSH
  84.  
  85.    RESULTS
  86.        Error -- if the Flush succeded, then io_Error will be null.
  87.                 If the Flush failed, then the io_Error will be non-zero.
  88.  
  89.  
  90. serial.device/command/Query                     serial.device/command/Query
  91.  
  92.    NAME
  93.        Query -- query serial port/line status
  94.  
  95.    FUNCTION
  96.        This command return the status of the serial port lines and
  97.        registers. The number of unread bytes in the serial device's
  98.        read buffer is shown in io_Actual.
  99.  
  100.     The break send & received flags are cleared by a query, and
  101.     whenever a read IORequest is returned with a error
  102.     in io_Error.
  103.  
  104.    IO REQUEST
  105.        io_Message      mn_ReplyPort initialized
  106.        io_Device       preset by OpenDevice
  107.        io_Unit         preset by OpenDevice
  108.        io_Command      SDCMD_QUERY
  109.  
  110.    RESULTS
  111.        io_Status        BIT  ACTIVE  FUNCTION
  112.  
  113.               LSB       0    ---    reserved
  114.                         1    ---    reserved
  115.                         2    high   parallel "sel" on the A1000
  116.                                     On the A500 & A2000, "sel" is also
  117.                                     connected to the serial port's
  118.                                     "Ring Indicator".  Be cautious when
  119.                                     making cables.
  120.                         3    low    Data Set Ready
  121.                         4    low    Clear To Send
  122.                         5    low    Carrier Detect
  123.                         6    low    Ready To Send
  124.                         7    low    Data Terminal Ready
  125.               MSB       8    high   hardware overrun
  126.                         9    high   break sent (most recent output)
  127.                        10    high   break received (as latest input)
  128.                        11    high   transmit x-OFFed       
  129.                        12    high   receive x-OFFed       
  130.                     13-15    ---    reserved
  131.  
  132.        io_Actual       set to count of unread input characters
  133.  
  134.        io_Error -- Query will always succeded.
  135.  
  136.  
  137. serial.device/command/Read                       serial.device/command/Read
  138.  
  139.    NAME
  140.        Read -- read input from serial port
  141.  
  142.    FUNCTION
  143.        This command causes a stream of characters to be read in from
  144.     the serial port buffer.  The number of characters is specified
  145.     in io_Length.
  146.  
  147.     The Query function can be used to check how many characters
  148.     are currently waiting in the serial port buffer.  If more characters
  149.     are requested than are currently available, the ioRequest
  150.     will be queued until it can be satisfied.
  151.  
  152.  
  153.     The best way to handle reads is to first Query to get the number
  154.     of characters currently in the buffer.  Then post a read request
  155.     for that number of characters (or the maximum size of your buffer).
  156.  
  157.     If zero characters are in the buffer, post a request
  158.     for 1 character.  When at least one is ready, the device will return
  159.     it.  Now start over with another Query.
  160.  
  161.     Before the program exits, it must be sure to AbortIO() then WaitIO()
  162.     any outstanding ioRequests.
  163.  
  164.    IO REQUEST
  165.        io_Message      A mn_ReplyPort is required
  166.        io_Device       set by OpenDevice
  167.        io_Unit         set by OpenDevice
  168.        io_Command      CMD_READ
  169.        io_Flags        If the IOB_QUICK bit is set, read will try
  170.             to complete the IO quickly
  171.        io_Length       number of characters to receive.
  172.        io_Data         pointer to buffer
  173.  
  174.    RESULTS
  175.        Error -- if the Read succeded, then io_Error will be null.
  176.            If the Read failed, then io_Error will be non-zero.
  177.          io_Error will indicate problems such as parity mismatch,
  178.          break, and buffer overrun.
  179.  
  180.    SEE ALSO
  181.     serial.device/command/Write
  182.     serial.device/command/Query
  183.     serial.device/command/SetParams
  184.  
  185.    BUGS
  186.     Having multiple outstanding read IORequests at any one time will
  187.     probably fail.
  188.  
  189.     Old documentation mentioned a mode where io_Length was set to -1.
  190.     If you want a NULL terminated read, use the io_TermArray instead.
  191.  
  192.  
  193. serial.device/command/Reset                     serial.device/command/Reset
  194.  
  195.    NAME
  196.        Reset -- reinitializes the serial port
  197.  
  198.    FUNCTION
  199.        This command resets the serial port to its freshly initialized
  200.        condition. It aborts all I/O requests both queued and current,
  201.        relinquishes the current buffer, obtains a new default sized
  202.        buffer, and sets the port's flags and parameters to their 
  203.        boot-up time default values. The functions places the reset
  204.        parameter values in the ioRequest block.
  205.  
  206.    IO REQUEST
  207.        io_Message      mn_ReplyPort initialized
  208.        io_Device       set by OpenDevice
  209.        io_Unit         set by OpenDevice
  210.        io_Command      CMD_RESET
  211.  
  212.    RESULTS
  213.        Error -- if the Reset succeded, then Error will be null.
  214.            If the Reset failed, then the Error will be non-zero.
  215.  
  216.  
  217. serial.device/command/SetParams             serial.device/command/SetParams
  218.  
  219.    NAME
  220.        SetParams -- change parameters for the serial port
  221.  
  222.    FUNCTION
  223.        This command allows the caller to change parameters for the
  224.        serial device. Except for xON-xOFF enable/disable, it will
  225.        reject a setparams call if any reads or writes are active 
  226.        or pending. 
  227.           Note specifically:
  228.  
  229.     1. Valid input for io_Baud is between 112 and 292000 baud inclusive;
  230.        asynchronous i/o above 32KB (especially on a busy system) may
  231.        be ambitious.  Note that a request for 110 baud should be rounded
  232.     to 112 baud... the hardware minimum.
  233.     2. The EOFMODE and QUEUEDBRK bits of io_SerFlags can be set/reset 
  234.        in the io_Rqst block without a call to SetParams. The SHARED 
  235.        and 7WIRE bits of io_SerFlags can be used in OpenDevice calls.
  236.        ALL OTHER PARAMETERS CAN ONLY BE CHANGED BY THE SetParams 
  237.        COMMAND.
  238.     3. RBufLen must be at least 64.
  239.     4. If not used, io_ExtFlags MUST be set to zero.
  240.     5. xON-xOFF is by default enabled. The XDISABLED bit is the only
  241.        parameter that can be changed via a SetParams call while the
  242.        device is active. Note that this will return the value
  243.        SerErr_DevBusy in the io_Error field.
  244.     6. If trying to run MIDI, you should set the RAD_BOOGIE bit of
  245.        io_SerFlags to eliminate unneeded overhead. Specifically, this skips
  246.        checks for parity, x-OFF handling, character lengths other than
  247.        8 bits, and testing for a break signal. Setting RAD_BOOGIE will
  248.        also set the XDISABLED bit.
  249.        Note that writing data (that's already in MIDI format) at MIDI rates
  250.        is easily accomplished. Using this driver alone for MIDI reads may,
  251.        however, may not be reliable, due to MIDI timestamping requirements,
  252.        and possibility of overruns in a busy multitasking and/or display
  253.        intensive environment.
  254.     7. If you select mark or space parity (see io_ExtFlags in serial.h),
  255.        this will cause the SERB_PARTY_ON bit to be set, and the setting
  256.        of SERB_PARTY_ODD to be ignored.
  257.     8. For best results, set the RAD_BOOGIE flag whenever possible.  See
  258.     #6 for details.
  259.     9. Note that at this time parity is *not* calculated for the xON-xOFF
  260.     characters.  If you have a system that is picky about the parity of
  261.     these, you must set your own xON-xOFF characters in io_CtlChar.
  262.  
  263.    IO REQUEST
  264.        io_Message      mn_ReplyPort initialized
  265.        io_Device       preset by OpenDevice
  266.        io_Unit         preset by OpenDevice
  267.        io_Command      SDCMD_SETPARAMS (0x0B)
  268.               NOTE that the following fields are filled in by Open 
  269.                        to reflect the serial device's current configuration.
  270.        io_CtlChar      a longword containing byte values for the
  271.                        xON,xOFF,INQ,ACK fields (respectively)
  272.                        (INQ/ACK not used at this time)
  273.        io_RBufLen      length in bytes of input buffer
  274.               NOTE that any change in buffer size causes the
  275.                        current buffer to be deallocated and a new,
  276.                        correctly sized one to be allocated. Thusly,
  277.                        the CONTENTS OF THE OLD BUFFER ARE LOST.
  278.        io_ExtFlags     additional serial flags (bitdefs in devices/serial.h)
  279.             mark & space parity may be specified here.
  280.        io_Baud         baud rate for reads AND writes. (See 1 above)
  281.        io_BrkTime      duration of break signal in MICROseconds
  282.        io_TermArray    ASCII descending-ordered 8-byte array of
  283.                        termination characters. If less than 8 chars
  284.                        used, fill out array w/lowest valid value.
  285.                        Terminators are checked only if EOFMODE bit of
  286.                        io_Serflags is set. (e.g. x512F040303030303 )
  287.        io_ReadLen      number of bits in read word (1-8) not including parity
  288.        io_WriteLen     number of bits in write word (1-8) "      "       "
  289.        io_StopBits     number of stop bits (0, 1 or 2)
  290.        io_SerFlags     see devices/serial.h for bit equates, NOTE that x00
  291.                        yields exclusive access, xON/OFF-enabled, no
  292.                        parity checking, 3-wire protocol and TermArray
  293.                        inactive.
  294.  
  295.    RESULTS
  296.        Error -- if the SetParams succeded, then Error will be null.
  297.            If the SetParams failed, then the Error will be non-zero.
  298.  
  299.    SEE ALSO
  300.     serial.device/function/OpenDevice
  301.     serial.device/function/BeginIO
  302.  
  303.  
  304. serial.device/command/Start                     serial.device/command/Start
  305.  
  306.    NAME
  307.        Start -- restart paused I/O over the serial port
  308.  
  309.    FUNCTION
  310.        This function restarts all current I/O on the serial port by 
  311.        sending an xON to the "other side", and submitting a "logical
  312.        xON" to "our side", if/when appropriate to current activity.
  313.  
  314.    IO REQUEST
  315.        io_Message      mn_ReplyPort initialized
  316.        io_Device       set by OpenDevice
  317.        io_Unit         set by OpenDevice
  318.        io_Command      CMD_START
  319.  
  320.    RESULTS
  321.  
  322.    SEE ALSO
  323.        serial.device/command/Stop
  324.  
  325.  
  326. serial.device/command/Stop                       serial.device/command/Stop
  327.  
  328.    NAME
  329.        Stop -- pause all current I/O over the serial port
  330.  
  331.    FUNCTION
  332.        This command halts all current I/O on the serial port by 
  333.        sending an xOFF to the "other side", and submitting a "logical
  334.        xOFF" to "our side", if/when appropriate to current activity.
  335.  
  336.    IO REQUEST
  337.        io_Message      mn_ReplyPort initialized
  338.        io_Device       set by OpenDevice
  339.        io_Unit         set by OpenDevice
  340.        io_Command      CMD_STOP
  341.  
  342.    RESULTS
  343.  
  344.    SEE ALSO
  345.        serial.device/command/Start
  346.  
  347.  
  348. serial.device/command/Write                     serial.device/command/Write
  349.  
  350.    NAME
  351.        Write -- send output to serial port
  352.  
  353.    FUNCTION
  354.        This command causes a stream of characters to be written out
  355.        the serial port. The number of characters is specified in
  356.        io_Length, unless -1 is used, in which case output is sent until
  357.        a null(0x00) is encountered. 
  358.  
  359.    IO REQUEST
  360.        io_Message      must have mn_ReplyPort initialized
  361.        io_Device       set by OpenDevice
  362.        io_Unit         set by OpenDevice
  363.        io_Command      CMD_WRITE
  364.        io_Flags        Set IOF_QUICK to try quick I/O
  365.        io_Length       number of characters to transmit, or if set
  366.                        to -1 transmit until null encountered in buffer
  367.        io_Data         pointer to block of data to transmit
  368.  
  369.    RESULTS
  370.        Error -- if the Write succeded, then io_Error will be null.
  371.            If the Write failed, then the io_Error will be non-zero.
  372.  
  373.    SEE ALSO
  374.     serial.device/command/setParams
  375.     serial.device/command/Read
  376.  
  377.  
  378. serial.device/function/AbortIO               serial.device/function/AbortIO
  379.  
  380.    NAME
  381.        AbortIO(ioRequest) -- abort an I/O request
  382.                A1
  383.    FUNCTION
  384.     This is a direct function call to the serial.device, and an exec
  385.     call.  Most programs will simply call exec.
  386.  
  387.     This function attempts to aborts a specified read or write request.
  388.     If the request is active, it is stopped immediately. If the request is
  389.     queued, it is painlessly removed.
  390.  
  391.     After AbortIO(), you must generally do a WaitIO().
  392.  
  393.    INPUTS
  394.        iORequest  -- pointer to the IORequest Block that is to be aborted.
  395.  
  396.    RESULTS
  397.        io_Error -- if the Abort succeded, then io_Error will be #IOERR_ABORTED
  398.  
  399.            (-2) and the request will be flagged as aborted (bit 5 of 
  400.            io_Flags is set).  If the Abort failed, then the Error will be zero.
  401.  
  402.    SEE ALSO
  403.     serial.device/function/BeginIO
  404.  
  405.  
  406. serial.device/function/BeginIO               serial.device/function/BeginIO
  407.  
  408.    NAME
  409.        BeginIO(ioRequest),deviceNode -- start up an I/O process
  410.                 A1        A6
  411.    FUNCTION
  412.        This is a direct function call to the device.  It is intended for
  413.        more advanced programmers.  See exec's DoIO() and SendIO() for
  414.        the normal method of calling devices.
  415.  
  416.        This function initiates a I/O request made to the serial
  417.        device. Other than read or write, the functions are performed 
  418.        synchronously, and do not depend on any interrupt handling 
  419.        logic (or it's associated discontinuities), and hence should
  420.        be performed as IO_QUICK.
  421.        With some exceptions, reads and writes are merely initiated by 
  422.        BeginIO, and thusly return to the caller as begun, not completed.
  423.        Completion is signalled via the standard ReplyMsg routine.
  424.        Multiple requests are handled via FIFO queueing.
  425.        One exception to this non-QUICK handling of reads and writes
  426.        is for READS when:
  427.          - IO_QUICK bit is set
  428.          - There are no pending read requests
  429.          - There is already enough data in the input buffer to satisfy
  430.            this I/O Request immediately.
  431.        In this case, the IO_QUICK flag is not cleared, and the request
  432.        is completed by the time it returns to the caller. There is no
  433.        ReplyMsg or signal bit activity in this case.
  434.           
  435.    INPUTS
  436.        ioRequest  -- pointer to an I/O Request Block of size 
  437.            io_ExtSerSize (see serial.i for size/definition), 
  438.            containing a valid command in io_Command to process,
  439.            as well as the command's other required parameters.
  440.        deviceNode -- pointer to the "serial.device", as found in
  441.            the IO_DEVICE of the ioRequest.
  442.  
  443.    RESULTS
  444.        io_Error -- if the BeginIO succeded, then Error will be null.
  445.            If the BeginIO failed, then the Error will be non-zero.
  446.            I/O errors won't be reported until the io completes.
  447.  
  448.    SEE ALSO
  449.     devices/serial.h
  450.  
  451.  
  452. serial.device/function/CloseDevice       serial.device/function/CloseDevice
  453.  
  454.    NAME
  455.        CloseDevice -- close the serial port
  456.  
  457.    SYNOPSIS
  458.        CloseDevice(deviceNode)
  459.                     A1
  460.    FUNCTION
  461.        This is an exec call that terminates communication with the
  462.        serial device.  Upon closing, the device's input buffer is freed.
  463.  
  464.        Note that all IORequests MUST be complete before closing.
  465.     If any are pending, your program must AbortIO() then WaitIO()
  466.        to complete them.
  467.  
  468.    INPUTS
  469.        deviceNode - pointer to the device node, set by Open
  470.  
  471.    SEE ALSO
  472.        serial.device/function/Open
  473.  
  474.  
  475. serial.device/function/OpenDevice         serial.device/function/OpenDevice
  476.  
  477.    NAME
  478.        OpenDevice -- Request an opening of the serial device.
  479.  
  480.    SYNOPSIS
  481.        error = OpenDevice(SERIALNAME, unit, ioRequest, flags)
  482.        D0                 A0          D0    A1         D0
  483.  
  484.    FUNCTION
  485.        This is an exec call.  Exec will search for the serial.device, and
  486.        if found, will pass this call on to the device.
  487.  
  488.        Unless the shared-access bit (bit 5 of io_SerFlags) is set, 
  489.        exclusive use is granted and no other access to that unit is
  490.        allowed until the owner closes it.  All the serial-specific fields
  491.        in the ioRequest are initialized to their most recent values (or
  492.        the Preferences default, for the first time open).
  493.  
  494.        If support of 7-wire handshaking (i.e. RS232-C CTS/RTS protocol)
  495.        is required, set the 7WIRE bit in io_SerFlags before opening
  496.        the serial device.
  497.  
  498.    INPUTS
  499.        SERIALNAME    - pointer to literal string "serial.device"
  500.        unit          - Must be zero, or a user setable unit number.
  501.               (This field is used by multiple port controllers)
  502.                          Zero specifies the built-in serial port.
  503.        ioRequest     - pointer to an ioRequest block of size io_ExtSerSize
  504.                          to be initialized by the serial.device.
  505.                          (see devices/serial.h for the definition)
  506.                            NOTE use of io_SerFlags (see FUNCTION above)
  507.         IMPORTANT: The ioRequest block MUST be of size io_ExtSerSize !
  508.        flags         - Must be zero for future compatibility
  509.  
  510.    RESULTS
  511.        D0       - same as io_Error
  512.        io_Error  - If the Open succeded, then io_Error will be null.
  513.                    If the Open failed, then io_Error will be non-zero.
  514.        io_Device - A pointer to whatever device will handle the calls
  515.                    for this unit.  This pointer may be different depending
  516.                    on what unit is requested.
  517.  
  518.    BUGS
  519.     If 7-wire handshaking is specified, this enables a timeout "feature".
  520.     If the device holds off the computer for more than about 30-60
  521.     seconds, the device will return the write request with the error
  522.     SerErr_TimerErr.  Don't depend on this, however.  If you want a timeout,
  523.     set up the timer.device and wait for either timer, or serial IO to
  524.     complete.
  525.  
  526.    SEE ALSO
  527.     exec/CloseDevice
  528.     devices/serial.h
  529.  
  530.  
  531.